package com.studyweb.service;

/**
 * 验证码服务接口
 * 
 * <p>定义验证码相关的业务逻辑操作，包括：</p>
 * <ul>
 *   <li>生成验证码</li>
 *   <li>存储验证码</li>
 *   <li>验证验证码</li>
 *   <li>清除验证码</li>
 * </ul>
 * 
 * @author StudyWeb Team
 * @since 1.0.0
 */
public interface VerificationCodeService {

    /**
     * 生成验证码
     *
     * @return String 6位数字验证码
     */
    String generateCode();

    /**
     * 存储验证码
     *
     * @param email 邮箱地址，作为存储的key
     * @param code 验证码
     * @param expireMinutes 过期时间（分钟）
     * @return boolean 存储是否成功
     * @throws Exception 存储过程中可能出现的异常
     */
    boolean storeCode(String email, String code, int expireMinutes);

    /**
     * 验证验证码
     *
     * @param email 邮箱地址
     * @param code 用户输入的验证码
     * @return boolean 验证是否通过
     * @throws Exception 验证过程中可能出现的异常
     */
    boolean verifyCode(String email, String code);

    /**
     * 清除验证码
     *
     * @param email 邮箱地址
     * @return boolean 清除是否成功
     * @throws Exception 清除过程中可能出现的异常
     */
    boolean clearCode(String email);

    /**
     * 检查验证码是否存在
     *
     * @param email 邮箱地址
     * @return boolean 验证码是否存在且未过期
     * @throws Exception 检查过程中可能出现的异常
     */
    boolean hasCode(String email);

    /**
     * 获取验证码剩余有效时间
     *
     * @param email 邮箱地址
     * @return long 剩余有效时间（秒），-1表示不存在或已过期
     * @throws Exception 查询过程中可能出现的异常
     */
    long getCodeTtl(String email);
}